---
title: "identity_already_exists"
description: "The requested identity already exists"
---

<Danger>
err:unkey:data:identity_already_exists
</Danger>


```json Example
{
  "meta": {
    "requestId": "req_2c9a0jf23l4k567"
  },
  "error": {
    "detail": "An identity with this external ID already exists",
    "status": 409,
    "title": "Conflict",
    "type": "https://unkey.com/docs/api-reference/errors-v2/unkey/data/identity_already_exists"
  }
}
```

## What Happened?

This error occurs when you're trying to create an identity with an external ID that already exists in your Unkey workspace. External IDs must be unique within a workspace to avoid confusion and maintain data integrity.

Common scenarios that trigger this error:
- Creating an identity with an external ID that's already in use
- Re-creating a previously deleted identity with the same external ID
- Migration or import processes that don't check for existing identities
- Duplicate API calls due to retries or network issues

Here's an example of a request that would trigger this error:

```bash
# Attempting to create an identity with an external ID that already exists
curl -X POST https://api.unkey.com/v2/identities.createIdentity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "externalId": "user_123",
    "meta": {
      "name": "John Doe",
      "email": "john@example.com"
    }
  }'
```

## How To Fix

When you encounter this error, you have several options:

1. **Use a different external ID**: If creating a new identity, use a unique external ID
2. **Update the existing identity**: If you want to modify an existing identity, use the update endpoint instead
3. **Get the existing identity**: If you just need the identity information, retrieve it rather than creating it
4. **Implement upsert logic**: Use a get-or-create pattern in your code

Here's how to update an existing identity:

```bash
curl -X POST https://api.unkey.com/v2/identities.updateIdentity \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer unkey_YOUR_API_KEY" \
  -d '{
    "externalId": "user_123",
    "meta": {
      "name": "John Doe",
      "email": "updated_email@example.com"
    }
  }'
```

Or implement a get-or-create pattern in your code:

```javascript
// Pseudocode for get-or-create pattern
async function getOrCreateIdentity(externalId, meta) {
  try {
    // Try to create the identity
    return await createIdentity(externalId, meta);
  } catch (error) {
    // If it already exists (409 error), get it instead
    if (error.status === 409) {
      return await getIdentity(externalId);
    }
    // Otherwise, rethrow the error
    throw error;
  }
}
```

## Common Mistakes

- **Not checking for existing identities**: Failing to check if an identity already exists before creating it
- **Retry loops**: Repeatedly trying to create the same identity after a failure
- **Case sensitivity**: Not accounting for case sensitivity in external IDs
- **Cross-environment duplication**: Using the same external IDs across development and production environments

## Related Errors
- [err:unkey:data:identity_not_found](./identity_not_found) - When the requested identity doesn't exist
- [err:unkey:authorization:insufficient_permissions](../authorization/insufficient_permissions) - When you don't have permission to perform operations on identities
